home *** CD-ROM | disk | FTP | other *** search
Text File | 1999-01-26 | 51.8 KB | 1,421 lines |
- Info file: geomview, -*-Text-*-
- produced by texinfo-format-buffer
- from file: geomview.tex
-
-
- File: geomview Node: Lighting Panel, Prev: Materials Panel, Up: Appearance, Next: Cameras
-
- The Lighting Panel
- ------------------
-
- The *Lighting* panel controls the number, position, and color of
- the light sources used in shading.
-
- The *Lighting* panel is different from the *Appearance* and
- *Material* panels in that it always works with the base
- appearance. This is because it usually makes sense to use the same set
- of lights for drawing all objects in your scene.
-
-
- *LIGHTS*
- The *LIGHTS* browser shows the currently selected light. Changes
- made using the other widgets on this panel apply to this light. There
- is always at least one light, the ambient light.
-
- *Intensity*
- This slider controls the intensity of the current light.
-
- *Color*
- This button brings up a color chooser which lets you select the color
- of the current light.
-
- *Add*
- This button adds a light.
-
- *Delete*
- This button deletes the current light.
-
- *Show Lights*
- This button lets you see and change the positions of the light sources
- in a camera window. Each light is drawn as long cylinder which is
- supposed to remind you of a light beam. When you click on the
- *Show Lights* button Geomview goes into "light edit" mode, during
- which you can rotate current light by holding down the left mouse button
- and moving the mouse. Lights placed in this way are infinitely distant,
- so what you are changing is the angular position. Click on the
- *Show Lights* button again to return to the previous motion mode
- and to quit drawing the light beams.
-
- *Done*
- This button dismisses the *Lighting* panel.
-
-
- Geomview's *Appearance*, *Materials*, and *Lighting*
- panels are constructed to allow you to easily do most of the appearance
- related things that you might want to do. The appearance hierarchy that
- Geomview supports internally, however, is very complex and there are
- certain operations that you cannot do with the panels. The Geomview
- command language (gcl) provides complete support for appearance operations.
- In particular, the `merge-baseap' command can be used to change the
- base appearance (which, except for lighting, cannot be changed by
- Geomview's panels). The `merge-ap' command can be used to change
- an individual geom's appearance. Appearances can also be specified in
- OOGL files; for details, *Note Appearances::.
-
-
- File: geomview Node: Cameras, Prev: Lighting Panel, Up: Interaction, Next: Saving
-
- Cameras
- =======
-
- A camera in Geomview is the object that corresponds to a camera window.
- By default there is only one camera, but it is possible to have as many
- as you want. You can control certain aspects of the way the world is
- drawn in each camera window via the *Cameras* panel.
- If the target object is a camera, the *Cameras* panel affects that
- camera. If the target object is not a camera, the *Cameras* panel
- affects the "current camera". The current camera is the camera of
- the window that the mouse cursor is in, or was in most recently if the
- cursor is not in a camera window. Thus, if you use the keyboard
- shortcuts for the actions in the *Cameras* panel while the cursor
- is in a camera window, the actions apply to that camera, unless you have
- explicitly selected another camera.
-
- To create new camera windows, use the `v+' keyboard shortcut,
- or see the *File* menu on the *Main* panel.
-
-
- *Single-Buffering*
- Normally, geomview windows are *double-buffered*: geomview draws the
- next picture into a hidden window, then switches buffers to make
- it visible all at once. On many systems, the memory for the hidden buffer
- comes from stealing half the bits in each screen pixel, reducing the color
- resolution. When single-buffering is enabled, the window flickers as each
- scene is being drawn, but you may get smoother images with reduced grainy
- dithering artifacts. Single-buffering is possible if Geomview is compiled with
- GL or OpenGL, but not with plain-X graphics.
-
- *Dither*
- Many displays offer less than the 24 bits per pixel (8 bits each of red, green,
- and blue) conventionally needed to show smooth gradations of color.
- When trying to show a color not accurately available on the display,
- Geomview normally *dithers*, choosing pixel colors sometimes brighter,
- sometimes darker than the desired value, so that the average color over an area
- is a better approximation to the true color than a single pixel could be.
- Effectively this loses spatial resolution to gain color resolution.
- This isn't always desirable, though. Turning *Dither* off
- gives less grainy, but less accurately colored, images.
-
- *Software Shading*
- This button controls whether Geomview does shading calculations in software.
- The default is to let the hardware handle them, and in Euclidean space
- this is almost certainly best because it is faster. In hyperbolic and
- spherical space, however, the shading calculations that the hardware
- does are incorrect. Click this button to turn on correct but slower
- software shading.
-
- *Background Color*
- This button brings up a color chooser which you can use to set the
- background color of the camera's window.
-
- *PROJECTION*
- This browser lets you pick between perspective and orthogonal projection
- for this camera.
-
- *Near clip*
- This determines the distance in world coordinates of the near clipping
- plane from the eye point. It must be a positive number.
-
- *Far clip*
- This determines the distance in world coordinates of the far clipping
- plane from the eye point. It must be a positive number and in general
- should be larger than the *Near clip* value.
-
- *FOV*
- This is the camera's field of view, measured in its shorter direction.
- In perspective mode, it is an angle in degrees. In orthographic mode,
- it is the linear size of the field of view. This number can be modified
- with the mouse in *Cam Zoom* mode.
-
- *Focal Length*
- The focal length is intended to suggest the distance from the camera to
- an imaginary plane of interest. Its value is used when switching
- between orthographic and perspective views (and during stereo viewing),
- so as to preserve apparent size of objects lying at the focal distance
- from the camera. Focal length also affects interpretation of mouse-based
- translational motions. Speed of forward motion (in translate, fly and
- orbit modes) is proportional to focal length; and objects lying at the
- focal distance from the camera translate laterally at the same rate as
- the mouse cursor. Finally, in N-D projection mode, cameras are displaced
- back by the focal distance from the 3-D projection of the world origin.
-
- *Lines Closer*
- This number has to do with the way lines are drawn. Normally Geomview's
- z-buffering algorithm can get confused when drawing lines that lie
- exactly on surfaces (such as the edges of an object); due to machine
- round-off error, sometimes the lines appear to be in front of the
- surface and sometimes they appear behind it. The *Lines Closer*
- value is a fudge factor --- Geomview nudges all the lines that it draws
- closer to the camera by this amount. The number should be a small
- integer; try 5 or 10. 0 turns this feature off completely. Choosing
- too large a value will make lines visible even though they should be
- hidden.
-
- *SPACE MODEL*
- This determines the model used to draw the world. It is most useful in
- hyperbolic and spherical spaces. You probably don't need to touch this
- browser if you stay in Euclidean space. For more information about
- these models, *Note Non-Euclidean Geometry::.
- *Virtual*
- This is the default model and represents the natural view from inside
- the space.
-
- *Projective*
- The projective model of hyperbolic and spherical space. Geoms move
- under isometries of the space, and cameras move by Euclidean motions.
- By default in the projective model, the Euclidean unit sphere is drawn.
- In hyperbolic space this is the sphere at infinity. In Euclidean space
- the projective model is the same as the virtual model except that the
- sphere is drawn by default.
-
- *Conformal*
- The conformal model of hyperbolic and spherical space. Geoms move under
- isometries of the space, and cameras move by Euclidean motions. In
- Euclidean space, the conformal model amounts to inverting everything in
- the unit sphere.
-
- *Draw Sphere*
- This controls whether Geomview draws the unit sphere. By default the
- unit sphere appears in the projective and conformal models. In
- hyperbolic space this is the sphere at infinity. In spherical space it
- is the equatorial sphere.
-
- *Done*
- This button dismisses the *Cameras* panel.
-
-
- File: geomview Node: Saving, Prev: Cameras, Up: Interaction, Next: Commands
-
- Saving your work
- ================
-
- Geomview's *Save* panel lets you store Geomview objects and other
- information in files that you can read back into Geomview or other
- programs.
- To use the *Save* panel you select the desired format in the
- browser next to the word *Save*, enter the name of the object you
- want to save in the text field next to the word *for*, and enter
- the name of the file you wish to save to in the long text field next to
- the word *in*. You can then either hit `RET' or click
- on the *OK* button. When the file has been written, the *Save*
- panel disappears. If you want to dismiss the *Save* panel without
- writing a file, click the *Cancel* button.
-
- If you specify `-' as the file name, Geomview will write the file
- to standard output, i.e. in the shell window from which you invoked
- Geomview.
-
- The possible formats are given below. The kind of object that can
- be written with each format is given in parentheses.
-
-
- *Commands (any object)*
- This write a file of gcl commands containing all information about
- the object. Loading this file later will restore the object as well as
- all other information about it, such as appearance, transformations,
- etc.
-
- *Geometry alone (geom)*
- This writes an OOGL file containing just the geometry of the object.
-
- *Geometry [in world] (geom)*
- This writes an OOGL file containing just the geometry of the object,
- transformed under Geomview's current transformation for this object.
- Use this if you have moved the object from its initial position and want
- to save the new position relative to the world.
-
- *Geometry [in universe] (geom)*
- This writes an OOGL file containing just the geometry of the geom,
- transformed under both the object's transformaton and the world's
- transformation.
-
- *RMan [->tiff] (camera)*
- Writes a RenderMan file which when rendered creates a tiff image.
-
- *RMan [->frame] (camera)*
- Writes a RenderMan file which when rendered causes an image to appear in
- a window on the screen.
-
- *SGI snapshot (camera)*
- Write an SGI raster file. A bell rings when the snapshot is complete.
- Only available on SGI systems.
-
- *PPM Screen snapshot (camera)*
- Take a snapshot of the given window and save it as a PPM image.
- If you specify a string beginning with a vertical bar (`|')
- as the file name, it's interpreted as a Bourne shell command
- to which the PPM data should be piped, as in
- `| pnmtotiff > snap.tiff' or `| convert -geometry 50% ppm:- snap.gif'.
-
- PPM screen snapshots are only available with GL and Open GL,
- not plain X graphics. The window should be entirely on the screen.
- Geomview will ensure that no other windows cover it while the snapshot
- is taken.
-
- *PPM software snapshot (camera)*
- Writes a snapshot of that window's current view, as a PPM image, to the
- given file. The file name may be a Bourne shell command preceded by a vertical
- bar (`|'), as with the PPM screen snapshot. The software snapshot, though,
- is produced by using a built-in software renderer (related to the X-windows
- renderer). It doesn't matter whether the window is visible or not,
- and doesn't depend on GL or OpenGL. It also doesn't support some features,
- such as texture mapping.
-
- *Postscript snapshot (camera)*
- Writes a Postscript snapshot of the camera's view. It's made by
- breaking up the scene into lines and polygons, sorting by depth, and
- generating Postscript lines and polygons for each one. Advantages over
- pixel-based snapshot images: resolution is very high, so edges
- look sharp even on high-resolution printers, or comparable-resolution images
- are typically much more compact. Disadvantages: depth-sorting
- gives good results on some scenes, but can be wildly wrong as a hidden-surface
- removal algorithm for other scenes. Also, Postscript doesn't offer
- smoothly interpolated shading, only flat shading for each facet.
-
- *Camera (camera)*
- Writes an OOGL file of a camera.
-
- *Transform [to world] (any object)*
- Writes an OOGL transform file giving Geomview's transform for the object.
-
- *Transform [to universe] (any object)*
- Writes an OOGL transform file giving a transform which is the
- composition of Geomview's transform for the object and the transform for
- the world.
-
- *Window (camera)*
- Writes an OOGL window file for a camera.
-
- *Panels*
- Writes a gcl file containing commands which record
- the state of all the Geomview panels. Loading this file later will
- restore the positions of all the panels.
-
-
- File: geomview Node: Commands, Prev: Saving, Up: Interaction, Next: Keyboard Shortcuts
-
- The Commands Panel
- ==================
-
- The *Commands* panel lets you type in a gcl command. When
- you hit `RET', Geomview interprets the command and prints any
- resulting output or error messages on standard output. You can edit the
- text and hit `RET' as many times as you like, in general,
- whenever you hit `RET' with the cursor in the *Commands*
- panel, Geomview tries to interpret whatever text you have typed in the
- text field as a command.
-
- The *Obscure* panel is for relatively obscure things that don't
- really belong on any of the other panels. In the present version of
- Geomview, the *Obscure* panel includes the *NORMALIZE GEOMETRY*
- browser, which controls the kind of geometry normalization that Geomview does,
- and several buttons affecting motion style.
- [Move this.]
- Normalization is a kind of scaling; Geomview can scale an object so that
- it fits within a certain region. The main point of normalization is to
- allow you to easily view all of an object without having to worry about
- how big it is. We are gradually replacing Geomview's normalization
- feature with more robust camera positioning features. In general, the
- best way to make sure you are seeing all of an object is to use the
- *Look At* button on the *Tools* panel. Normalization may
- be completely replaced by this and other features in a future version of
- Geomview.
-
- Normalization is a property that applies to each geom separately. The
- *NORMALIZE GEOMETRY* browser affects the normalization property
- of target geom. If the target geom is "World", it affects all geoms.
-
-
- *None*
- Do no normalization.
-
- *Individual*
- Normalize this geom to fit within a unit sphere.
-
- *Sequence*
- This resembles "Individual", except when an object is changing. Then,
- "Individual" tightly fits the bounding box around the object whenever it
- changes and normalizes accordingly, while "Sequence" normalizes the
- union of all variants of the object and normalizes accordingly.
-
- *Keep*
- This leaves the current normalization transform unchanged when the
- object changes. It may be useful to apply "Individual" or "Sequence"
- normalization to the first version of a changing object to bring
- it in view, then switch to "Keep".
-
-
- File: geomview Node: Keyboard Shortcuts, Prev: Commands, Up: Interaction, Next: OOGL File Formats
-
- Keyboard Shortcuts
- ==================
-
- Most actions that you can do through Geomview's panels have equivalent
- keyboard shortcuts so that you can do the same action by typing a
- sequence of keys on the keyboard. This is useful for advanced users who
- are familiar with Geomview's capabilities and want to work quickly
- without having to have lots of panels cluttering up the screen.
- Keyboard shortcuts usually are indicated in square brackets ([ ]) near
- the corresponding item in a panel. For example, the keyboard shortcut
- for *Rotate* mode is 'r'; this is indicated by "[r]" appearing
- before the word "Rotate" in the *MOTION MODE* browser. To
- use this keyboard shortcut just hit the `r' key while the mouse
- cursor is in any Geomview window. You don't need to press the `RET'
- or `SPACE' keys.
-
- Some keyboard shortcuts consist of more than one key. In these cases
- just type the keys one after the other, with no `RET'
- afterwards. Keyboard shortcuts are case sensitive. You can cancel a
- multi-key keyboard shortcut that you have started by typing any invalid
- key, for example the space bar.
-
- Keyboard commands apply while the cursor is in any camera window and
- most control panels.
-
- Many keyboard shortcuts allow numeric arguments which you type as a
- prefix to the command key(s). For example, the shortcut for
- *Near clip* in the camera panel is `v n'. To set the near
- clip plane to `0.5', type `0.5vn'. Commands that don't take a
- numeric prefix toggle or reset the current value.
-
- Most commands allow one of the following selection prefixes. If none is
- provided the command applies to the target object.
-
- `g'
- world geom
- `g#'
- #'th geom
- `g*'
- All geoms
- `c'
- current camera
- `c#'
- #'th camera
- `c*'
- All cameras
-
- For example, `g4af' means toggle the face drawing of object
- *g4*.
-
- Simply typing a selection prefix, like `g4', doesn't yet select an object;
- that only happens when a command, like `ae', follows the prefix.
- To select an object as the target without doing anything else to it,
- use the `p' command. So `g3p' selects object g3.
-
- The text field in the upper left corner of the *Main* panel
- shows the state of the current keyboard shortcut.
-
- In addition to the keyboard shortcuts for the panel commands, there is
- also a shortcut for picking a target object: type the short name of the
- object followed by `p'. For example, to select object *g3*,
- type `g 3 p'. This only works with the short names --- the ones
- that appear in square brackets ([ ]) in the *Targets* browser of
- the *Main* panel.
-
- Below is a summary of all keyboard shortcuts.
-
- Draw
- `af'
-
- Faces
- `ae'
-
- Edges
- `an'
-
- Normals
- `ab'
-
- Bounding Boxes
- `aV'
-
- Vectors
- Shading
-
- `0as'
-
- Constant
- `1as'
-
- Flat
- `2as'
-
- Smooth
- `3as'
-
- Smooth, non-lighted
- `aT'
-
- allow transparency
- `at'
-
- texture mapping
- Other
-
- `av'
-
- eVert normals: always face viewer
- `#aw'
-
- Line Width (pixels)
- `aC'
-
- handle concave polygons
- `#vc'
-
- edges Closer than faces (try 5-100)
- Color
-
- `Cf'
-
- faces
- `Ce'
-
- edges
- `Cn'
-
- normals
- `Cb'
-
- bounding boxes
- `CB'
-
- background
- Motions
-
- `r'
-
- rotate
- `t'
-
- translate
- `z'
-
- zoom FOV
- `f'
-
- fly
- `o'
-
- orbit
- `s'
-
- scale
- `w'
-
- recenter target
- `W'
-
- recenter all
- `h'
-
- halt
- `H'
-
- halt all
- `@'
-
- select center of motion (e.g. `g 3 @')
- `L'
-
- Look At object
- Viewing
-
- `0vp'
-
- Orthographic view
- `1vp'
-
- Perspective view
- `vd'
-
- Draw other views' cameras
- `#vv'
-
- field of View
- `#vn'
-
- near clip distance
- `#vf'
-
- far clip distance
- `v+'
-
- add new camera
- `vx'
-
- cursor on/off
- `vb'
-
- backfacing poly cull on/off
- `#vl'
-
- focal length
- `v~'
-
- Software shading on/off
- Panels
-
- `Pm'
-
- Main
- `Pa'
-
- Appearance
- `Pl'
-
- Lighting
- `Po'
-
- Obscure
- `Pt'
-
- Tools
- `Pc'
-
- Cameras
- `PC'
-
- Commands
- `Pf'
-
- Files
- `Ps'
-
- Save
- `P-'
-
- read commands from tty
- `PA'
-
- Credits ("about")
- Lights
-
- `ls'
-
- show lights
- `le'
-
- edit lights
- Space
-
- `me'
-
- Euclidean
- `mh'
-
- Hyperbolic
- `ms'
-
- Spherical
- Model
-
- `mv'
-
- Virtual
- `mp'
-
- Projective
- `mc'
-
- Conformal
- Other
-
- `0N'
-
- normalizaton: none
- `1N'
-
- normalization: each
- `2N all'
-
- normalization: all
- `ui'
-
- motion: Inertia
- `uc'
-
- motion: Constrain to axis
- `uo'
-
- motion: object's Own coordinates
- `<'
-
- `Pf'
-
- load geometry/command file
- `dd'
-
- delete target object
- `>'
-
- `Ps'
-
- save state to file
- `TV'
-
- NTSC mode toggle
- `p'
-
- pick as target object (e.g. `g 3 p')
- With no prefix, selects the object under the
- mouse cursor (like double-clicking the right mouse)
-
- File: geomview Node: OOGL File Formats, Prev: Keyboard Shortcuts, Up: Top, Next: Conventions
-
- OOGL File Formats
- *****************
-
- The objects that you can load into Geomview are called OOGL objects.
- OOGL stands for "Object Oriented Graphics Library"; it is the library
- upon which Geomview is built.
-
- There are many different kinds of OOGL objects. This chapter gives
- syntactic descriptions of file formats for OOGL objects.
-
- Examples of most file types live in Geomview's `data/geom'
- directory.
-
- * Menu:
-
- * Conventions:: Conventions.
- * Object File Formats:: Object File Formats.
- * Non-geometric objects:: Non-geometric objects.
-
- File: geomview Node: Conventions, Prev: OOGL File Formats, Up: OOGL File Formats, Next: Common syntax
-
- Conventions
- ===========
-
- * Menu:
-
- * Common syntax:: Syntax Common to All OOGL File Formats.
- * File names:: File Names.
- * Vertices:: Vertices.
- * Surface normal directions:: Surface normal directions.
- * Transformation matrices:: Transformation matrices.
- * Binary format:: Binary format.
- * References:: Embedded objects and external-object references.
- * Appearances:: Appearances.
-
- File: geomview Node: Common syntax, Prev: Conventions, Up: Conventions, Next: File names
-
- Syntax Common to All OOGL File Formats
- --------------------------------------
-
- Most OOGL object file formats are free-format ASCII --- any amount of
- white space (blanks, tabs, newlines) may appear between tokens (numbers,
- key words, etc.). Line breaks are almost always insignificant, with a
- couple of exceptions as noted. Comments begin with # and continue to
- the end of the line; they're allowed anywhere a newline is.
-
- Binary formats are also defined for several objects; *Note Binary format::, and the individual object descriptions.
-
- Typical OOGL objects begin with a key word designating object type,
- possibly with modifiers indicating presence of color information etc.
- In some formats the key word is optional, for compatibility with file
- formats defined elsewhere. Object type is then determined by
- guessing from the file suffix (if any) or from the data itself.
-
- Key words are case sensitive. Some have optional prefix letters
- indicating presence of color or other data; in this case the order of
- prefixes is significant, e.g. `CNMESH' is meaningful but
- `NCMESH' is invalid.
-
- File: geomview Node: File names, Prev: Common syntax, Up: Conventions, Next: Vertices
-
- File Names
- ----------
-
- When OOGL objects are read from disk files, the OOGL library uses the
- file suffix to guess at the file type.
-
- If the suffix is unrecognized, or if no suffix is available (e.g. for an
- object being read from a pipe, or embedded in another OOGL object), all
- known types of objects are tried in turn until one accepts the data as
- valid.
-
- File: geomview Node: Vertices, Prev: File names, Up: Conventions, Next: Surface normal directions
-
- Vertices
- --------
-
- Several objects share a common style of representing vertices with
- optional per-vertex surface-normal and color. All vertices within an
- object have the same format, specified by the header key word.
-
- All data for a vertex is grouped together (as opposed to e.g. giving
- coordinates for all vertices, then colors for all vertices, and so on).
-
- The syntax is
-
- `X Y Z'
- (3-D floating-point vertex coordinates) or
- `X Y Z W'
- (4-D floating-point vertex coordinates)
-
- optionally followed by
-
- `NX NY NZ'
- (normalized 3-D surface-normal if present)
-
- optionally followed by
-
- `R G B A'
- (4-component floating-point color if present, each component in range
- 0..1. The A (alpha) component represents opacity: 0 transparent, 1
- opaque.)
-
- optionally followed by
- `S T'
- `or'
- `S T U'
-
- (two or three texture-coordinate values).
-
- Values are separated by white space, and line breaks
- are immaterial.
-
- Letters in the object's header key word must appear in a specific order;
- that's the reverse of the order in which the data is given for each vertex.
- So a `CN4OFF' object's vertices contain first the 4-component space
- position, then the 3-component normal, finally the 4-component color.
- You can't change the data order by changing the header key word; an
- `NCOFF' is just not recognized.
-
- File: geomview Node: Surface normal directions, Prev: Vertices, Up: Conventions, Next: Transformation matrices
-
- Surface normal directions
- -------------------------
-
- Geomview uses normal vectors to determine how an object is shaded.
- The direction of the normal is significant in this calculation.
-
- When normals are supplied with an object, the direction of the normal
- is determined by the data given.
-
- When normals are not supplied with the object, Geomview computes normal
- vectors automatically; in this case normals point toward the side from
- which the vertices appear in counterclockwise order.
-
- On parametric surfaces (Bezier patches), the normal at point P(u,v)
- is in the direction dP/du cross dP/dv.
-
- File: geomview Node: Transformation matrices, Prev: Surface normal directions, Up: Conventions, Next: Binary format
-
- Transformation matrices
- -----------------------
-
- Some objects incorporate 4x4 real matrices for homogeneous object
- transformations. These matrices act by multiplication on the right of
- vectors. Thus, if p is a 4-element row vector representing homogeneous
- coordinates of a point in the OOGL object, and A is the 4x4 matrix, then
- the transformed point is p' = p A. This matrix convention is common in
- computer graphics; it's the transpose of that often used in mathematics,
- where points are column vectors multiplied on the right of matrices.
-
-
- Thus for Euclidean transformations, the translation components appear in
- the fourth row (last four elements) of A. A's last column (4th, 8th,
- 12th and 16th elements) are typically 0, 0, 0, and 1 respectively.
-
- File: geomview Node: Binary format, Prev: Transformation matrices, Up: Conventions, Next: References
-
- Binary format
- -------------
-
- Many OOGL objects accept binary as well as ASCII file formats.
- These files begin with the usual ASCII token (e.g. `CQUAD')
- followed by the word `BINARY'.
- Binary data begins at the byte following the first newline after
- `BINARY'. White space and a single comment may intervene, e.g.
-
- OFF BINARY # binary-format "OFF" data follows
-
- Binary data comprise 32-bit integers and 32-bit IEEE-format floats, both
- in big-endian format (i.e., with most significant byte first). This is
- the native format for 'int's and 'float's on Sun-3's, Sun-4's, and
- Irises, among others.
-
- Binary data formats resemble the corresponding ASCII formats, with ints
- and floats in just the places you'd expect. There are some exceptions
- though, specifically in the `QUAD', `OFF' and `COMMENT'
- file formats. Details are given in the individual file format
- descriptions. *Note QUAD::, *Note OFF::, and *Note COMMENT::.
-
- Binary OOGL objects may be freely mixed in ASCII object streams:
-
- LIST
- { = MESH BINARY
- ... binary data for mesh here ...
- }
- { = QUAD
- 1 0 0 0 0 1 0 1 0 0 1 0
- }
-
- Note that ASCII data resumes immediately following the last byte of
- binary data.
-
- Naturally, it's impossible to embed comments inside a binary-format OOGL
- object, though comments may appear in the header before the beginning of
- binary data.
-
- File: geomview Node: References, Prev: Binary format, Up: Conventions, Next: Appearances
-
- Embedded objects and external-object references
- -----------------------------------------------
-
- Some object types (`LIST', `INST') allow references to other
- OOGL objects, which may appear literally in the data stream, be loaded
- from named disk files, or be communicated from elsewhere via named
- objects. Gcl commands also accept geometry in these forms.
-
- The general syntax is
-
- <oogl-object> ::=
- [ "{" ]
- [ "define" `symbolname' ]
- [ "appearance" `appearance' ]
- [ ["="] `object-keyword' ...
- | "<" `filename'
- | ":" `symbolname' ]
- [ "}" ]
-
- where "quoted" items are literal strings (which appear without the
- quotes), [bracketed] items are optional, and | denotes alternatives.
- Curly braces, when present, must match; the outermost set of curly
- braces is generally required when the object is in a larger context,
- e.g. when it is part of a larger object or embedded in a Geomview
- command stream.
-
- For example, each of the following three lines:
- { define fred QUAD 1 0 0 0 0 1 0 1 0 1 0 0 }
-
- { appearance { +edge } LIST { < "file1" } { : fred } }
-
- VECT 1 2 0 2 0 0 0 0 1 1 2
- is a valid OOGL object. The last example is only valid when it is
- delimited unambiguously by residing in its own disk file.
-
- The "<" construct causes a disk file to be read. Note that this isn't a
- general textual "include" mechanism; a complete OOGL object must appear
- in the referenced file.
-
- Files read using "<" are sought first in the directory of the file which
- referred to them, if any; failing that, the normal search path (set by
- Geomview's `load-path' command) is used. The default search looks
- first in the current directory, then in the Geomview data directories.
-
- The ":" construct allows references to symbols, created with
- `define'. A symbol's initial value is a null object. When a
- symbol is (re)defined, all references to it are automatically changed;
- this is a crucial part of the support for interprocess communication.
- Some future version of the documentation should explain this better...
-
- Again, white space and line breaks are insignificant, and "#" comments
- may appear anywhere.
-
-
- File: geomview Node: Appearances, Prev: References, Up: Conventions, Next: Texture Mapping
-
- Appearances
- -----------
-
- Geometric objects can have associated "appearance" information,
- specifying shading, lighting, color, wireframe vs. shaded-surface
- display, and so on. Appearances are inherited through object
- hierarchies, e.g. attaching an appearance to a `LIST' means that the
- appearance is applied to all the `LIST''s members.
-
- Some appearance-related properties are relegated to "material" and
- "lighting" substructures. Take care to note which properties belong to
- which structure.
-
- Here's an example appearance structure including values for all
- attributes. Order of attributes is unimportant. As usual, white space
- is irrelevant. Boolean attributes may be preceded by "+" or "-" to turn
- them on or off; "+" is assumed if only the attribute name appears.
- Other attributes expect values.
-
- A "*" prefix on any attribute, e.g. "*+edge" or "*linewidth 2"
- or "material { *diffuse 1 1 .25 }", selects "override" status for
- that attribute.
-
- appearance {
- +face # (Do) draw faces of polygons. On by default.
- -edge # (Don't) draw edges of polygons
- +vect # (Do) draw VECTs. On by default.
- -transparent # (Disable) transparency. enabling transparency
- # does NOT result in a correct Geomview picture,
- # but alpha values are used in RenderMan snapshots.
- -normal # (Do) draw surface-normal vectors
- normscale 1 # ... with length 1.0 in object coordinates
-
- +evert # do evert polygon normals where needed so as
- # to always face the camera
-
- -texturing # (Disable) texture mapping
- -backcull # (Don't) discard clockwise-oriented faces
- -concave # (Don't) expect and handle concave polygons
- -shadelines # (Don't) shade lines as if they were lighted cylinders
- # These four are only effective where the graphics system
- # supports them, namely on GL and Open GL.
-
- -keepcolor # Normally, when N-D positional coloring is enabled as
- # with geomview's (ND-color ...) command, all
- # objects' colors are affected. But, objects with the
- # "+keepcolor" attribute are immune to N-D coloring.
-
- shading smooth # or "shading constant" or "shading flat" or
- # or "shading csmooth".
- # smooth = Gouraud shading, flat = faceted,
- # csmooth = smoothly interpolated but unlighted.
-
- linewidth 1 # lines, points, and edges are 1 pixel wide.
-
- patchdice 10 10 # subdivide Bezier patches this finely in u and v
-
- material { # Here's a material definition;
- # it could also be read from a file as in
- # "material < file.mat"
-
- ka 1.0 # ambient reflection coefficient.
- ambient .3 .5 .3 # ambient color (red, green, blue components)
- # The ambient contribution to the shading is
- # the product of ka, the ambient color,
- # and the color of the ambient light.
-
- kd 0.8 # diffuse-reflection coefficient.
- diffuse .9 1 .4 # diffuse color.
- # (In "shading constant" mode, the surface
- # is colored with the diffuse color.)
-
- ks 1.0 # specular reflection coefficient.
- specular 1 1 1 # specular (highlight) color.
- shininess 25 # specular exponent; larger values give
- # sharper highlights.
-
- backdiffuse .7 .5 0 # back-face color for two-sided surfaces
- # If defined, this field determines the diffuse
- # color for the back side of a surface.
- # It's implemented by the software shader, and
- # by hardware shading on GL systems which support
- # two-sided lighting, and under Open GL.
-
- alpha 1.0 # opacity; 0 = transparent (invisible), 1 = opaque.
- # Ignored when transparency is disabled.
-
- edgecolor 1 1 0 # line & edge color
-
- normalcolor 0 0 0 # color for surface-normal vectors
- }
-
- lighting { # Lighting model
-
- ambient .3 .3 .3 # ambient light
-
- replacelights # "Use only the following lights to
- # illuminate the objects under this
- # appearance."
- # Without "replacelights", any lights listed
- # are added to those already in the scene.
-
- # Now a collection of sample lights:
- light {
- color 1 .7 .6 # light color
- position 1 0 .5 0 # light position [distant light]
- # given in homogeneous coordinates.
- # With fourth component = 0,
- # this means a light coming from
- # direction (1,0,.5).
- }
-
- light { # Another light.
- color 1 1 1
- position 0 0 .5 1 # light at finite position ...
- location camera # specified in camera coordinates.
- # (Since the camera looks toward -Z,
- # this example places the light
- # .5 unit behind the eye.)
- # Possible "location" keywords:
- # global light position is in world (well, universe) coordinates
- # This is the default if no location specified.
- # camera position is in the camera's coordinate system
- # local position is in the coordinate system where
- # the appearance was defined
- }
- } # end lighting model
- texture {
- clamp st # or "s" or "t" or "none"
- file lump.tiff # file supplying texture-map image
- alphafile mask.pgm.Z # file supplying transparency-mask image
- apply blend # or "modulate" or "decal"
- transform 1 0 0 0 # surface (s,t,0,1) * tfm -> texture coords
- 0 1 0 0
- 0 0 1 0
- .5 0 0 1
-
- background 1 0 0 1 # relevant for "apply blend"
- }
- } # end appearance
-
-
- There are rules for inheritance of appearance attributes when several
- are imposed at different levels in the hierarchy.
-
- For example, Geomview installs a backstop appearance which provides
- default values for most parameters; its control panels install other
- appearances which supply new values for a few attributes; user-supplied
- geometry may also contain appearances.
-
- The general rule is that the child's appearance (the one closest to the
- geometric primitives) wins.
- Further, appearance controls with "override" status
- (e.g. *+face or material { *diffuse 1 1 0 })
- win over those without it.
-
- Geomview's appearance controls use the "override" feature so as to be
- effective even if user-supplied objects contain their own appearance settings.
- However, if a user-supplied object contains an appearance field with
- override status set, that property will be immune to Geomview's controls.
-
- File: geomview Node: Texture Mapping, Prev: Appearances, Up: Conventions, Next: Object File Formats
-
- Texture Mapping
- ---------------
-
- Some platforms support texture-mapped objects.
- (On those which don't, attempts to use texture mapping are silently
- ignored.) A texture is specified as part of an appearance structure,
- as in *Note Appearances::. Briefly, one provides a texture image,
- which is considered to lie in a square in `(s,t)' parameter space in
- the range 0 <= s <= 1, 0 <= t <= 1. Then one provides a geometric primitive,
- with each vertex tagged with `(s,t)' texture coordinates. If texturing
- is enabled, the appropriate portion of the texture image is pasted onto
- each face of the textured object.
-
- There is (currently) no provision for inheritance of part of a texture
- structure; if the `texture' keyword is mentioned in an appearance,
- it supplants any other texture specification.
-
- The appearance attribute `texturing' controls whether textures are
- used; there's no performance penalty for having texture { ... } fields
- defined when texturing is off.
-
- The available fields are:
-
- clamp none -or- s -or- t -or- st
- Determines the meaning of texture coordinates outside the range 0..1.
- With `clamp none', the default, coordinates are interpreted
- modulo 1, so (s,t) = (1.25,0), (.25,0), and (-.75,0) all refer to
- the same point in texture space. With `s' or `t' or
- `st', either or both of s- or t-coordinates less than 0 or
- greater than 1 are clamped to 1 or 0, respectively.
-
- file filename
- alphafile filename
- Specifies image file(s) containing the texture.
- The `file' file's image specifies color or lightness information;
- the `alphafile' if present, specifies a transparency ("alpha") mask;
- where the mask is zero, pixels are simply not drawn.
- Several image file formats are available; the file type must be
- indicated by the last few characters of the file name:
- .ppm or .ppm.Z or .ppm.gz 24-bit 3-color image in PPM format
- .pgm or .pgm.Z or .pgm.gz 8-bit grayscale image in PGM format
- .sgi or .sgi.Z or .sgi.gz 8-bit, 24-bit, or 32-bit SGI image
- .tiff 8-bit or 24-bit TIFF image
- .gif GIF image
- (Though 4-channel TIFF images are possible, and could
- represent both color and transparency information in one image,
- that's not supported in geomview at present.)
- For this feature to work, some programs must be available in
- geomview's search path:
- zcat for .Z files
- gzip for .gz files
- tifftopnm for .tiff files
- giftoppm for .gif files
-
- If an `alphafile' image is supplied, it must be the same size
- as the `file' image.
-
-
- apply modulate -or- blend -or- decal
- Indicates how the texture image is applied to the surface.
- Here the "surface color" means the color that surface would have
- in the absence of texture mapping.
-
- With `modulate', the default, the texture color (or lightness,
- if textured by a gray-scale image) is multiplied by the surface color.
-
- With `blend', texture blends between the `background' color
- and the surface color. The `file' parameter must specify a
- gray-scale image. Where the texture image is 0, the surface color is
- unaffected; where it's 1, the surface is painted in the color given
- by `background'; and color is interpolated for intermediate values.
-
- With `decal', the `file' parameter must specify a
- 3-color image. If an `alphafile' parameter is present,
- its value interpolates between the surface color (where alpha=0)
- and the texture color (where alpha=1). Lighting does not affect the
- texture color in `decal' mode; effectively the texture is
- constant-shaded.
-
- background R G B A
- Specifies a 4-component color, with R, G, B, and A floating-point
- numbers normally in the range 0..1, used when `apply blend'
- is selected.
-
- transform `transformation-matrix'
- Expects a list of 16 numbers, or one of the other ways of representing
- a transformation (`: handlename' or `< filename').
- The 4x4 transformation matrix is applied to texture coordinates,
- in the sense of a 4-component row vector (s,t,0,1) multiplied on
- the left of the matrix, to produce new coordinates (s',t')
- which actually index the texture.
-
- File: geomview Node: Object File Formats, Prev: Texture Mapping, Up: OOGL File Formats, Next: QUAD
-
- Object File Formats
- ===================
-
- * Menu:
-
- * QUAD:: List of quadrilaterals.
- * MESH:: Rectangularly-connected mesh.
- * BBP and BEZ:: List of Bezier surface patches.
- * OFF:: Polyhedra: polygons with shared vertices.
- * VECT:: List of points and lines.
- * SKEL:: List of points and lines, with shared vertices.
- * SPHERE:: Sphere
- * INST:: Transformed Instance of another object.
- * LIST:: List of other objects.
- * TLIST:: Collection of 4x4 transformation matrices.
- * GROUP:: Obsolete format for collections of objects.
- * DISCGRP:: Discrete Group objects.
- * COMMENT:: Comment object, for caching information.
-
-
- File: geomview Node: QUAD, Prev: Object File Formats, Up: Object File Formats, Next: MESH
-
- QUAD: collection of quadrilaterals
- ----------------------------------
-
- The conventional suffix for a `QUAD' file is `.quad'.
-
- The file syntax is
-
- [C][N][4]QUAD -or- [C][N][4]POLY # Key word
- VERTEX VERTEX VERTEX VERTEX # 4*N vertices for some N
- VERTEX VERTEX VERTEX VERTEX
- ...
-
- The leading key word is `[C][N][4]QUAD' or `[C][N][4]POLY',
- where the optional `C' and `N' prefixes indicate that each vertex
- includes colors and normals respectively. That is, these files
- begin with one of the words
-
- `QUAD' `CQUAD' `NQUAD' `CNQUAD' `POLY'
- `CPOLY' `NPOLY' `CNPOLY'
-
- (but not `NCQUAD' or `NCPOLY'). `QUAD' and `POLY'
- are synonymous; both forms are allowed just for compatibility with
- ChapReyes.
-
- Following the key word is an arbitrary number of groups of four
- vertices, each group describing a quadrilateral. See the Vertex syntax
- above. The object ends at end-of-file, or with a closebrace if
- incorporated into an object reference (see above).
-
- A `QUAD BINARY' file format is accepted; *Note Binary format::. The
- first word of binary data must be a 32-bit integer giving the number of
- quads in the object; following that is a series of 32-bit floats,
- arranged just as in the ASCII format.
-
- File: geomview Node: MESH, Prev: QUAD, Up: Object File Formats, Next: BBP and BEZ
-
- MESH: rectangularly-connected mesh
- ----------------------------------
-
- The conventional suffix for a `MESH' file is `.mesh'.
-
- The file syntax is
-
- [U][C][N][Z][4][u][v][n]MESH # Key word
- [NDIM] # Space dimension, present only if nMESH
- NU NV # Mesh grid dimensions
- # NU*NV vertices, in format specified
- # by initial key word
- VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU-1,0)
- VERTEX(0,1) ... VERTEX(NU-1,1)
- ...
- VERTEX(0,NV-1) ... VERTEX(NU-1,NV-1)
-
- The key word is `[U][C][N][Z][4][u][v][n]MESH'.
- The optional prefix characters mean:
-
- `U'
- Each vertex includes a 3-component texture space parameter.
- The first two components are the usual `S' and `T' texture
- parameters for that vertex; the third should be specified as zero.
- `C'
- Each vertex (see Vertices above) includes a 4-component color.
- `N'
- Each vertex includes a surface normal vector.
- `Z'
- Of the 3 vertex position values, only the Z component is present; X and
- Y are omitted, and assumed to equal the mesh (u,v) coordinate so X
- ranges from 0 .. (Nu-1), Y from 0 .. (Nv-1) where Nu and Nv are the mesh
- dimensions -- see below.
- `4'
- Vertices are 4D, each consists of 4 floating values. `Z' and
- `4' cannot both be present.
- `u'
- The mesh is wrapped in the u-direction, so the
- (0,v)'th vertex is connected to the (NU-1,v)'th for all v.
- `v'
- The mesh is wrapped in the v-direction, so the (u,0)'th vertex is
- connected to the (u,NV-1)'th for all u. Thus a u-wrapped or
- v-wrapped mesh is topologically a cylinder, while a uv-wrapped mesh is a
- torus.
- `n'
- Specifies a mesh whose vertices live in a higher dimensional space.
- The dimension follows the "MESH" keyword. Each vertex then has NDIM
- components.
-
- Note that the order of prefix characters is significant; a colored,
- u-wrapped mesh is a `CuMESH' not a `uCMESH'.
-
- Following the mesh header are integers NU and NV,
- the dimensions of the mesh.
-
- Then follow NU*NV vertices, each in the form given by the header.
- They appear in v-major order, i.e. if we name each vertex by (u,v)
- then the vertices appear in the order
-
- (0,0) (1,0) (2,0) (3,0) ... (NU-1,0)
- (0,1) (1,1) (2,1) (3,1) ... (NU-1,1)
- ...
- (0,Nv-1) ... (NU-1,NV-1)
-
- A `MESH BINARY' format is accepted; *Note Binary format::. The
- values of NU and NV are 32-bit integers; all other values
- are 32-bit floats.
-
- File: geomview Node: BBP and BEZ, Prev: MESH, Up: Object File Formats, Next: OFF
-
- Bezier Surfaces
- ---------------
-
- The conventional file suffixes for Bezier surface files are `.bbp'
- or `.bez'. A file with either suffix may contain either type of
- patch.
-
- Syntax:
-
- [ST]BBP -or- [C]BEZ<NU><NV><ND>[_ST]
- # NU, NV are u- and v-direction
- # polynomial degrees in range 1..6
- # ND = dimension: 3->3-D, 4->4-D (rational)
- # (The '<' and '>' do not appear in the input.)
- # NU,NV,ND are each a single decimal digit.
- # BBP form implies NU=NV=ND=3 so BBP = BEZ333.
-
- # Any number of patches follow the header
- # (NU+1)*(NV+1) patch control points
- # each 3 or 4 floats according to header
- VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU,0)
- VERTEX(0,1) ... VERTEX(NU,1)
- ...
- VERTEX(0,NV) ... VERTEX(NU,NV)
-
- # ST texture coordinates if mentioned in header
- `S'(u=0,v=0) `T'(0,0) `S'(0,NV) `T'(0,NV)
- `S'(NU,0) `T'(NU,0) `S'(NU,NV) `T'(NU,NV)
-
- # 4-component float (0..1) R G B A colors
- # for each patch corner if mentioned in header
- `RGBA'(0,0) `RGBA'(0,NV)
- `RGBA'(NU,0) `RGBA'(NU,NV)
-
- These formats represent collections of Bezier surface patches, of
- degrees up to 6, and with 3-D or 4-D (rational) vertices.
-
- The header keyword has the forms `[ST]BBP' or
- `[C]BEZ<NU><NV><ND>[_ST]' (the '<' and '>' are
- not part of the keyword.
-
- The `ST' prefix on `BBP', or `_ST' suffix on
- `BEZuvn', indicates that each patch includes four pairs of
- floating-point texture-space coordinates, one for each corner of the
- patch.
-
- The `C' prefix on `BEZuvn' indicates a colored patch,
- including four sets of four-component floating-point colors (red, green,
- blue, and alpha) in the range 0..1, one color for each corner.
-
- NU and NV, each a single digit in the range 1..6, are the
- patch's polynomial degree in the u and v direction respectively.
-
- ND is the number of components in each patch vertex, and must be
- either `3' for 3-D or `4' for homogeneous coordinates, that
- is, rational patches.
-
- `BBP' patches are bicubic patches with 3-D vertices, so `BBP'
- = `BEZ333' and `STBBP' = `BEZ333_ST'.
-
- Any number of patches follow the header. Each patch comprises a series
- of patch vertices, followed by optional (s,t) texture coordinates,
- followed by optional (r,g,b,a) colors.
-
- Each patch has (NU+1)*(NV+1) vertices in v-major order, so that if we
- designate a vertex by its control point indices (u,v) the order is
- (0,0) (1,0) (2,0) ... (NU,0)
- (0,1) (1,1) (2,1) ... (NU,1)
- ...
- (0,NV) ... (NU,NV)
- with each vertex containing either 3 or 4 floating-point numbers
- as specified by the header.
-
- If the header calls for ST coordinates, four pairs of floating-point
- numbers follow: the texture-space coordinates for the (0,0),
- (NU,0), (0,NV), and (NU,NV) corners of the
- patch, respectively.
-
- If the header calls for colors, four four-component (red, green, blue,
- alpha) floating-point colors follow, one for each patch corner.
-
- The series of patches ends at end-of-file, or with a closebrace if
- incorporated in an object reference.
-
-